docs: add HTTP API, SDK, and operations/policy reference docs#10
Merged
Merged
Conversation
Add three new reference documents covering subsystems introduced in the v1.1 rollout that had no dedicated documentation: - docs/http-api.md: all /v1/* routes with request/response shapes, auth model (loopback vs. Bearer token), confidence level table, error format, and common error codes. - docs/sdk.md: FlightdeckClient and AsyncFlightdeckClient usage guide covering constructor params, authentication, all public methods, error handling, custom httpx client injection, and constraints. - docs/operations-and-policy.md: operations layer architecture (single code path shared by CLI/HTTP/SDK), compute_diff internals (cost formula, cross-agent invariant), promote/rollback flow (first-promotion path, audit ledger, pointer atomicity), Policy model, confidence tiers, zero-threshold overrides, and a common errors/remedies table. Update README.md Documentation section to link all three docs. Update DEVELOPMENT.md Verify section to reference http-api.md and sdk.md. Co-authored-by: Gottam Sai Bharath <Gsbreddy@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Add three new reference documents for subsystems introduced in the v1.1 rollout (HTTP routes, Python SDK,
flightdeck.operations) that had no dedicated documentation. UpdateREADME.mdandDEVELOPMENT.mdto link them.Why
The v1.1 commit (
c8e2abc) shippedFlightdeckClient/AsyncFlightdeckClient, a structured server routes layer, andoperations.pyas the unified action backend. These are now the primary integration points for teams automating release governance, but they had no usage documentation — developers had to read source code to understand request shapes, auth requirements, confidence tiers, or error handling.Changes
docs/http-api.md— all/v1/*routes with request/response shapes, auth model (loopback vs. Bearer token), confidence level table, Swagger UI pointer, error format.docs/sdk.md—FlightdeckClient/AsyncFlightdeckClientusage guide: constructor params, authentication, all public methods with parameter descriptions, error handling, customhttpx.Clientinjection, constraints.docs/operations-and-policy.md— operations layer architecture (single code path shared by CLI/HTTP/SDK),compute_diffinternals (cost formula, cross-agent invariant), promote/rollback flow (first-promotion path, audit ledger, pointer atomicity),Policymodel field reference, confidence tiers, zero-threshold overrides, SQLite schema summary, common errors + remedies table.README.md— new "Documentation" links for all three files.DEVELOPMENT.md— added references tohttp-api.mdandsdk.mdin the Verify section.Validation
uv sync --frozen --extra devuv run python -m ruff check src tests— all checks passeduv run python -m pytest— 73 passedweb/src/changes — static build not requiredSchema / Storage Impact
Risk
Documentation only — no Python source, schema, or static asset changes.
Notes
All documented behavior is verified against the actual source:
operations.py,ledger.py,models.py,server/routes/, andsdk/client.py.